IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/g_man/cat3/OpenGL/glubuild3dmipmaps.z/glubuild3dmipmaps

Text File | 2001-04-17 | 22.6 KB | 199 lines

gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



NNNNAAAAMMMMEEEE
     gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss - builds a three-dimensional mipmap


CCCC SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
     GLint gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss( GLenum _t_a_r_g_e_t,
                              GLint _i_n_t_e_r_n_a_l_F_o_r_m_a_t,
                              GLsizei _w_i_d_t_h,
                              GLsizei _h_e_i_g_h_t,
                              GLsizei _d_e_p_t_h,
                              GLenum _f_o_r_m_a_t,
                              GLenum _t_y_p_e,
                              const void *_d_a_t_a )


PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
     _t_a_r_g_e_t          Specifies the target texture.  Must be GGGGLLLL____TTTTEEEEXXXXTTTTUUUURRRREEEE____3333DDDD.

     _i_n_t_e_r_n_a_l_F_o_r_m_a_t  Requests the internal storage format of the texture
                     image.  Must be 1, 2, 3, 4, or one of the following
                     symbolic constants:  GGGGLLLL____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____AAAALLLLPPPPHHHHAAAA4444, GGGGLLLL____AAAALLLLPPPPHHHHAAAA8888,
                     GGGGLLLL____AAAALLLLPPPPHHHHAAAA11112222, GGGGLLLL____AAAALLLLPPPPHHHHAAAA11116666, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE4444,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE8888, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11116666,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE4444____AAAALLLLPPPPHHHHAAAA4444,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE6666____AAAALLLLPPPPHHHHAAAA2222, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE8888____AAAALLLLPPPPHHHHAAAA8888,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222____AAAALLLLPPPPHHHHAAAA4444, GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11112222____AAAALLLLPPPPHHHHAAAA11112222,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE11116666____AAAALLLLPPPPHHHHAAAA11116666, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY4444,
                     GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY8888, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY11112222, GGGGLLLL____IIIINNNNTTTTEEEENNNNSSSSIIIITTTTYYYY11116666, GGGGLLLL____RRRRGGGGBBBB,
                     GGGGLLLL____RRRR3333____GGGG3333____BBBB2222, GGGGLLLL____RRRRGGGGBBBB4444, GGGGLLLL____RRRRGGGGBBBB5555, GGGGLLLL____RRRRGGGGBBBB8888, GGGGLLLL____RRRRGGGGBBBB11110000,
                     GGGGLLLL____RRRRGGGGBBBB11112222, GGGGLLLL____RRRRGGGGBBBB11116666, GGGGLLLL____RRRRGGGGBBBBAAAA, GGGGLLLL____RRRRGGGGBBBBAAAA2222, GGGGLLLL____RRRRGGGGBBBBAAAA4444,
                     GGGGLLLL____RRRRGGGGBBBB5555____AAAA1111, GGGGLLLL____RRRRGGGGBBBBAAAA8888, GGGGLLLL____RRRRGGGGBBBB11110000____AAAA2222, GGGGLLLL____RRRRGGGGBBBBAAAA11112222, or
                     GGGGLLLL____RRRRGGGGBBBBAAAA11116666.

     _w_i_d_t_h, _h_e_i_g_h_t, _d_e_p_t_h
                     Specifies in pixels the width, height and depth
                     respectively, in pixels of the texture image.

     _f_o_r_m_a_t          Specifies the format of the pixel data.  Must be one of
                     GGGGLLLL____CCCCOOOOLLLLOOOORRRR____IIIINNNNDDDDEEEEXXXX, GGGGLLLL____DDDDEEEEPPPPTTTTHHHH____CCCCOOOOMMMMPPPPOOOONNNNEEEENNNNTTTT, GGGGLLLL____RRRREEEEDDDD, GGGGLLLL____GGGGRRRREEEEEEEENNNN,
                     GGGGLLLL____BBBBLLLLUUUUEEEE, GGGGLLLL____AAAALLLLPPPPHHHHAAAA, GGGGLLLL____RRRRGGGGBBBB, GGGGLLLL____RRRRGGGGBBBBAAAA, GGGGLLLL____BBBBGGGGRRRR, GGGGLLLL____BBBBGGGGRRRRAAAA,
                     GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE, or GGGGLLLL____LLLLUUUUMMMMIIIINNNNAAAANNNNCCCCEEEE____AAAALLLLPPPPHHHHAAAA.

     _t_y_p_e            Specifies the data type for _d_a_t_a.  Must be one of:
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE, GGGGLLLL____BBBBYYYYTTTTEEEE, GGGGLLLL____BBBBIIIITTTTMMMMAAAAPPPP, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT,
                     GGGGLLLL____SSSSHHHHOOOORRRRTTTT, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT, GGGGLLLL____IIIINNNNTTTT, GGGGLLLL____FFFFLLLLOOOOAAAATTTT,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV,
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222, or
                     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV.



                                                                        PPPPaaaaggggeeee 1111






gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



     _d_a_t_a            Specifies a pointer to the image data in memory.

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss builds a series of prefiltered three-dimensional
     texture maps of decreasing resolutions called a mipmap. This is used for
     the antialiasing of texture-mapped primitives.

     A return value of zero indicates success, otherwise a GLU error code is
     returned (see gggglllluuuuEEEErrrrrrrroooorrrrSSSSttttrrrriiiinnnngggg).

     Initially, the _w_i_d_t_h, _h_e_i_g_h_t and _d_e_p_t_h of _d_a_t_a are checked to see if they
     are a power of 2. If not, a copy of _d_a_t_a (not _d_a_t_a), is scaled up or down
     to the nearest power of 2. (If _w_i_d_t_h, _h_e_i_g_h_t or _d_e_p_t_h is exactly between
     powers of 2, then the copy of _d_a_t_a will scale upwards.) This copy will be
     used for subsequent mipmapping operations described below.  For example,
     if _w_i_d_t_h is 57, _h_e_i_g_h_t is 23 and _d_e_p_t_h is 24 then a copy of _d_a_t_a will
     scale up to 64 in width, down to 16 in height and up to 32 in depth,
     before mipmapping takes place.

     Then, proxy textures (see ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee3333DDDD) are used to determine if the
     implementation can fit the requested texture. If not, all three
     dimensions are continually halved until it fits.

     Next, a series of mipmap levels is built by decimating a copy of _d_a_t_a in
     half along all three dimensions until size 1 x 1 x 1 is reached. At each
     level, each texel in the halved mipmap level is an average of the
     corresponding eight texels in the larger mipmap level. (If exactly one of
     the dimensions is 1, four texels are averaged.  If exactly two of the
     dimensions are 1, two texels are averaged.)

     ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee3333DDDD is called to load each of these mipmap levels.  Level 0 is a
     copy of _d_a_t_a.  The highest level is log(max(width,height,depth)).  For
     example, if _w_i_d_t_h is 64, _h_e_i_g_h_t is 16 and _d_e_p_t_h is 32, and the
     implementation can store a texture of this size, the following mipmap
     levels are built: 64 x 16 x 32, 32 x 8 x 16, 16 x 4 x 8, 8 x 2 x 4,
     4 x 1 x 2, 2 x 1 x 1 and 1 x 1 x 1. These correspond to levels 0 through
     6, respectively.

     See the ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD reference page for a description of the acceptable
     values for _f_o_r_m_a_t parameter. See the ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss reference page for a
     description of the acceptable values for _t_y_p_e parameter.

NNNNOOOOTTTTEEEESSSS
     Note that there is no direct way of querying the maximum level. This can
     be derived indirectly via ggggllllGGGGeeeettttTTTTeeeexxxxLLLLeeeevvvveeeellllPPPPaaaarrrraaaammmmeeeetttteeeerrrr. First, query for the
     width, height and depth actually used at level 0.  (The width, height and
     depth may not be equal to _w_i_d_t_h, _h_e_i_g_h_t and _d_e_p_t_h respectively since
     proxy textures might have scaled them to fit the implementation.)  Then
     the maximum level can be derived from the formula
     log(max(width,height,depth)).





                                                                        PPPPaaaaggggeeee 2222






gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))          OOOOppppeeeennnnGGGGLLLL RRRReeeeffffeeeerrrreeeennnncccceeee          gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss((((3333GGGG))))



     gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss is only available if the GLU version is 1.3 or greater.

     Formats GGGGLLLL____BBBBGGGGRRRR, and GGGGLLLL____BBBBGGGGRRRRAAAA, and types GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888,
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV, GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222, and
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV are only available if the GL version is
     1.2 or greater.

EEEERRRRRRRROOOORRRRSSSS
     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is returned if _w_i_d_t_h, _h_e_i_g_h_t, or _d_e_p_t_h is < 1.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____EEEENNNNUUUUMMMM is returned if _i_n_t_e_r_n_a_l_F_o_r_m_a_t, _f_o_r_m_a_t, or _t_y_p_e is not
     legal.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____3333____3333____2222 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____BBBBYYYYTTTTEEEE____2222____3333____3333____RRRREEEEVVVV and _f_o_r_m_a_t is not GGGGLLLL____RRRRGGGGBBBB.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____6666____5555____RRRREEEEVVVV and _f_o_r_m_a_t is not GGGGLLLL____RRRRGGGGBBBB.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____4444____4444____4444____4444____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____5555____5555____5555____1111 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____SSSSHHHHOOOORRRRTTTT____1111____5555____5555____5555____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888 or
     GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____8888____8888____8888____8888____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor GGGGLLLL____BBBBGGGGRRRRAAAA.

     GGGGLLLLUUUU____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is returned if _t_y_p_e is GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____11110000____11110000____11110000____2222
     or GGGGLLLL____UUUUNNNNSSSSIIIIGGGGNNNNEEEEDDDD____IIIINNNNTTTT____2222____11110000____11110000____11110000____RRRREEEEVVVV and _f_o_r_m_a_t is neither GGGGLLLL____RRRRGGGGBBBBAAAA nor
     GGGGLLLL____BBBBGGGGRRRRAAAA.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     ggggllllDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee1111DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee2222DDDD, ggggllllTTTTeeeexxxxIIIImmmmaaaaggggeeee3333DDDD,
     gggglllluuuuBBBBuuuuiiiilllldddd1111DDDDMMMMiiiippppmmmmaaaappppssss, gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppssss, gggglllluuuuEEEErrrrrrrroooorrrrSSSSttttrrrriiiinnnngggg, ggggllllGGGGeeeettttTTTTeeeexxxxIIIImmmmaaaaggggeeee,
     ggggllllGGGGeeeettttTTTTeeeexxxxLLLLeeeevvvveeeellllPPPPaaaarrrraaaammmmeeeetttteeeerrrr, gggglllluuuuBBBBuuuuiiiilllldddd1111DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss, gggglllluuuuBBBBuuuuiiiilllldddd2222DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss,
     gggglllluuuuBBBBuuuuiiiilllldddd3333DDDDMMMMiiiippppmmmmaaaappppLLLLeeeevvvveeeellllssss














                                                                        PPPPaaaaggggeeee 3333